<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
Java representation of ECLiPSe data
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot043.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot041.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot045.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc77">8.3</A>&nbsp;&nbsp;Java representation of ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> data</H2><UL>
<LI><A HREF="embroot044.html#toc35">General correspondence between ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> and Java data types</A>
<LI><A HREF="embroot044.html#toc36">Atoms and compound terms</A>
<LI><A HREF="embroot044.html#toc37">Lists</A>
<LI><A HREF="embroot044.html#toc38">Floats and Doubles</A>
<LI><A HREF="embroot044.html#toc39">Integers</A>
<LI><A HREF="embroot044.html#toc40">Variables</A>
<LI><A HREF="embroot044.html#toc41">The <TT>equals()</TT> method</A>
</UL>

<A NAME="sec:ji-terms-in-java"></A>
<A NAME="@default171"></A>
The Java-ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> Interface uses a set of conventions and Java classes so that data
types common in ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> can be represented. Representing ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> data types is useful for:
<UL CLASS="itemize"><LI CLASS="li-itemize">
Constructing compound goals to be sent to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> for execution.
<LI CLASS="li-itemize">Deconstructing the results of ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>'s computation, which are returned as a compound goal.
<LI CLASS="li-itemize">Communicating compound terms and other data via queues<A NAME="@default172"></A>. 
</UL>
More details on these tasks will be provided in Sections
<A HREF="embroot045.html#sec:ji-calling-goals">8.4</A> and <A HREF="embroot046.html#sec:ji-using-queue-streams">8.5</A>, but it is first necessary to understand how ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> data is represented in Java.<BR>
<BR>
<A NAME="toc35"></A>
<H3 CLASS="subsection"><A NAME="htoc78">8.3.1</A>&nbsp;&nbsp;General correspondence between ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> and Java data types</H3>
<A NAME="sec:ji-type-correspondence"></A>
Not all ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> data types are represented: for example, at present
the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> type <TT>rational</TT> has no Java equivalent. However, all
the most useful ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> types have a corresponding Java class. Table
<A HREF="#tab:ec-java-data">8.1</A> gives the general correspondence between those
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> data types which are supported and the Java classes or
interfaces which are used to represent them. The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> types/Java
classes which appear in the table are those which map to or from 
the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> external data representation (EXDR)<A NAME="@default173"></A> definition.
<BLOCKQUOTE CLASS="table"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV>
<DIV CLASS="center">
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1>
<TR><TD ALIGN=left NOWRAP>ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> data type	 	</TD>
<TD ALIGN=left NOWRAP>Java class/interface 		</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>atom</TT>		</TD>
<TD ALIGN=left NOWRAP><I>Atom</I>			</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>compound</TT> 		</TD>
<TD ALIGN=left NOWRAP><I>CompoundTerm</I>		</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>integer</TT>		</TD>
<TD ALIGN=left NOWRAP><I>java.lang.Integer</I>	</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>			</TD>
<TD ALIGN=left NOWRAP><I>java.lang.Long</I>	</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>list</TT>		</TD>
<TD ALIGN=left NOWRAP><I>java.util.Collection</I>	</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>float</TT>		</TD>
<TD ALIGN=left NOWRAP><I>java.lang.Double</I>	</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>			</TD>
<TD ALIGN=left NOWRAP><I>java.lang.Float</I>		</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>string</TT>		</TD>
<TD ALIGN=left NOWRAP><I>java.lang.String</I>	</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>variable</TT>		</TD>
<TD ALIGN=left NOWRAP><I>null</I>	</TD>
</TR></TABLE>
</DIV>
<BR>
<BR>
<DIV CLASS="center">Table 8.1: <A NAME="tab:ec-java-data"></A>The correspondence between ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> and Java data types. The Java classes are within the <TT>com.parctechnologies.eclipse</TT> package unless otherwise specified.</DIV><BR>
<BR>
 
<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></BLOCKQUOTE>
The general rule is that you can send data to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> by passing
the relevant method an instance of the Java class corresponding to the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> data type you want on the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side. When data comes
back from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> it will be an instance of <I>java.lang.Object</I>
but this can be cast to the relevant Java class, which must either be
known beforehand or determined e.g. using the <TT>getClass()</TT> method.<BR>
<BR>
There are also a number of peculiarities for certain cases which we
now explain.<BR>
<BR>
<A NAME="toc36"></A>
<H3 CLASS="subsection"><A NAME="htoc79">8.3.2</A>&nbsp;&nbsp;Atoms and compound terms</H3>
<A NAME="sec:ji-atoms-and-terms"></A>
Atoms are simple: these are constructed in Java using the constructor
of the <I>Atom</I> class: the string parameter of the constructor
becomes the atom symbol. Although the Java interface <I>CompoundTerm</I> is
listed above, compound terms (except lists) are usually constructed
using the <I>CompoundTermImpl</I> class, which implements <I>CompoundTerm</I>. Incidentally, <I>Atom</I> also implements <I>CompoundTerm</I>, even though strictly speaking ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> atoms are not compound. Here is an
example of <I>CompoundTermImpl</I> at work:
<PRE CLASS="verbatim">
  // Construct a term in Java to represent the Eclipse term foo(a, b, 3).
  private static CompoundTerm construct_term()
  {
    Atom a = new Atom("a");
    Atom b = new Atom("b");
    Integer numberThree = new Integer(3);
    CompoundTerm theTerm = new CompoundTermImpl("foo", a, b, numberThree);

    return(theTerm);
  }
</PRE>This method is taken from the example Java program <A HREF="../examples/JavaInterface/DataExample1.java"><TT>DataExample1.java</TT></A>
which can be found in the examples directory <TT>&lt;eclipse_dir&gt;</TT><TT>/doc/examples/JavaInterface</TT>. The rest of the program sends
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> a goal which tells it to write the term created by <TT>construct_term()</TT> to <TT>stdout</TT>.<BR>
<BR>
In this example we use an <I>CompoundTermImpl</I> constructor whose
first parameter is a string which becomes the functor of the term. The
remaining parameters are instances of <I>java.lang.Object</I>. They may
be instances of any class or interface which appears in Table
<A HREF="#tab:ec-java-data">8.1</A>. These become the arguments of the term. <I>CompoundTermImpl</I> has a number of other convenient constructors. See
the API documentation for details of these.<BR>
<BR>
Note that the object returned by <TT>construct_term()</TT> is declared
not as a <I>CompoundTermImpl</I> but as a <I>CompoundTerm</I>. CompoundTerm is the Java interface for objects
representing compound terms. Anything which implements CompoundTerm
can be sent to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> as a compound term.<BR>
<BR>
Instead of using <I>CompoundTermImpl</I>, you may wish to implement
<I>CompoundTerm</I> yourself. The benefit of this is that you can pass
any object implementing <I>CompoundTerm</I> to an <TT>rpc</TT><A NAME="@default174"></A> invocation, and
it can supply a functor and arguments without the unnecessary creation
of another object. To do this you may wish to subclass <I>AbstractCompoundTerm</I>.<BR>
<BR>
<A NAME="toc37"></A>
<H3 CLASS="subsection"><A NAME="htoc80">8.3.3</A>&nbsp;&nbsp;Lists</H3>
Whenever you want to construct a list for ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> or deconstruct a
list coming from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, you use the <I>java.util.Collection</I>
interface. Look at the following method, taken from the example Java
program <A HREF="../examples/JavaInterface/DataExample2.java"><TT>DataExample2.java</TT></A> (which can be found in the examples
directory <TT>&lt;eclipse_dir&gt;</TT><TT>/doc/examples/JavaInterface</TT>).
<PRE CLASS="verbatim">
  // Construct a collection in Java to represent the Eclipse 
  // list [1, foo(3.5), bar].
  private static Collection construct_collection()
  {
      Collection theCollection = new LinkedList();

      theCollection.add(new Integer(1));
      theCollection.add(new CompoundTermImpl("foo", new Double(3.5)));
      theCollection.add(new Atom("bar"));

      return(theCollection);
  }
</PRE>
If you study, compile and run <TT>DataExample2.java</TT> you will see
that the collection is indeed translated into the required ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
list. You will also see that order is maintained in the sense that the
order of elements as they appear in the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> list will equal the
collection's iterator order (the converse is true if the data is
coming from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> to Java).<BR>
<BR>
Also note that the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> empty list (<TT>[]</TT>) is represented in
Java by the constant <I>java.util.Collections.EMPTY_LIST</I>.<BR>
<BR>
<A NAME="toc38"></A>
<H3 CLASS="subsection"><A NAME="htoc81">8.3.4</A>&nbsp;&nbsp;Floats and Doubles</H3>
The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> data type <TT>float</TT> is always converted to <I>java.lang.Double</I> in Java. However, ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> can be sent an instance
of <I>java.lang.Double</I> or <I>java.lang.Float</I>: both will be
converted to <TT>float</TT> in ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. One value of <I>java.lang.Double</I> and <I>java.lang.Float</I> has no counterpart in
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>: the not-a-number (NaN) value. Infinite values can be sent
in either direction.<BR>
<BR>
<A NAME="toc39"></A>
<H3 CLASS="subsection"><A NAME="htoc82">8.3.5</A>&nbsp;&nbsp;Integers</H3>
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> can be sent instances of either <I>java.lang.Integer</I>
(32-bit integers) or <I>java.lang.Long</I> (64-bit integers). Both of
these will be translated to type <TT>integer</TT> on the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side.
When ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> sends data to Java, it will decide between the two
classes depending on the number of bits needed for the integer. So for
example, if the number is small enough to fit in an Integer, that is
what will be returned. Note that therefore, the type of number
coming back from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> cannot be relied upon to be of one type or
the other if it could fall on either side of the 32-/64-bit boundary.<BR>
<BR>
If you require a set of numbers coming from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> to be all of
one Java type e.g. long, then the best approach is to cast the object
returned by ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> to an instance of <I>java.lang.Number</I> and
then invoke the appropriate conversion method e.g. <TT>longValue()</TT>.<BR>
<BR>
<A NAME="toc40"></A>
<H3 CLASS="subsection"><A NAME="htoc83">8.3.6</A>&nbsp;&nbsp;Variables</H3>
<A NAME="sec:ji-variables-null"></A>
The Java <I>null</I> token is used to represent any variables being
sent to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. All variables coming from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> will appear as
<I>null</I>. The limitations of this are discussed in more detail in
Section <A HREF="embroot045.html#sec:ji-calling-goals">8.4</A>.<BR>
<BR>
<A NAME="toc41"></A>
<H3 CLASS="subsection"><A NAME="htoc84">8.3.7</A>&nbsp;&nbsp;The <TT>equals()</TT> method</H3>
The <TT>equals()</TT> method has been overridden for <I>AbstractCompoundTerm</I> and therefore also for <I>Atom</I> and <I>CompoundTermImpl</I>. The implementation returns <TT>true</TT> iff the
parameter <I>Object</I> implements <I>CompoundTerm</I> and its functor
and arity are equal to those of the <I>AbstractCompoundTerm</I>, and
pairwise invocations of <TT>equals()</TT> return <TT>true</TT> between each
of the <I>AbstractCompoundTerm</I>'s arguments and the corresponding
argument of the parameter object.<BR>
<BR>
<HR>
<A HREF="embroot043.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot041.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot045.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
